[185] Update N cycle documentation by Sanketmandwal · Pull Request #342 · PecanProject/sipnet

Sanketmandwal · 2026-05-27T07:07:28Z

Summary

What: Updated nitrogen cycle documentation in docs/model-structure.md and docs/parameters.md to reflect the implemented N-cycle behavior.

Changes include:
- Added K_vol to Nitrogen Cycle Parameters
- Removed redundant documentation related to fN2O_vol
- Added fNLeach
- Updated nitrogen volatilization documentation and moved justification below the model description/equation
- Updated nitrogen leaching equation to:
  F^N_leach = N_min · φ · fN_leach
- Added:
  φ = min(F^W_drainage / W_WHC, 1)
- Updated documentation to reflect a single minN pool while preserving separate soil and litter mineralization fluxes
- Replaced future tense with present tense where appropriate
Motivation: The documentation did not fully match the implemented nitrogen cycle behavior and parameter definitions. This update aligns the documentation with the current implementation and removes outdated or redundant descriptions.

How was this change tested?

Previewed documentation locally using:

mkdocs serve

Verified documentation builds successfully.
Manually reviewed rendered pages for:
- Nitrogen Volatilization section
- Nitrogen Leaching section
- Nitrogen Cycle Parameters table
Reviewed git diff to confirm changes are limited to intended documentation updates.

No smoke tests or code execution changes were required since this PR only updates documentation.

Reproduction steps

Run:

mkdocs serve

Open:

http://127.0.0.1:8000/

Navigate to the updated nitrogen cycle documentation sections.

Related issues

Fixes Update documentation for N cycle #185

Checklist

Related issues are listed above.
PR title has the issue number in it
Tests added/updated for new features (if applicable)
Documentation updated (if applicable)
docs/CHANGELOG.md updated with noteworthy changes
Code formatted with clang-format (not applicable for documentation-only changes)

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates nitrogen-cycle documentation to reflect a single mineral nitrogen pool and clarifies volatilization/leaching parameter definitions and equations.

Changes:

Renames initial mineral N state symbol to a single shared $N_{\text{min},0}$ pool.
Rewrites nitrogen volatilization and leaching documentation (including justification and updated leaching scaling).
Adjusts temperature-response equation formatting and clarifies moisture-fraction wording.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
docs/parameters.md	Updates parameter table entries and nitrogen-cycle parameter definitions/units to match revised model description.
docs/model-structure.md	Updates nitrogen volatilization/leaching sections to reflect single $N_\text{min}$ pool and introduces $\phi$ scaling; minor equation formatting edits.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Alomir · 2026-06-05T16:48:24Z

+| Symbol                 | Parameter Name       | Definition                                                                                                                           | Units             | Notes                            |
+| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | -------------------------------- |
+| $K_\text{vol}$         | nVolatilizationFrac  | Nitrogen volatilization rate constant that determines the maximum rate of N volatilization as a proportion of available $N_\text{min}$ | $\text{day}^{-1}$ | \eqref{eq:n_vol}                 |
+| $f^N_{\text{leach}}$   | nLeachingFrac        | Fraction of $N_\text{min}$ available to be leached, applied after scaling by $\phi = \min(F^W_\text{drainage}/W_\text{WHC}, 1)$      | unitless          | \eqref{eq:n_leach}               |


Yes, nLeachingFrac should have units of day^-1 (per day); this should be updated here and in state.h

Updated the units in state.h to match the documentation (per day)

Alomir · 2026-06-05T16:50:23Z


 \begin{equation}
-F^N_\text{leach} = N_\text{min} \cdot F^W_{drainage} \cdot f_{N leach}
+F^N_\text{leach} = N_\text{min} \cdot \phi \cdot f_{N leach}


f^N_\text{leach} should be used everywhere.

Alomir · 2026-06-05T16:50:37Z

+where:
+
+\begin{equation}
+\phi = \min\left(\frac{F^W_\text{drainage}}{W_\text{WHC}}, 1\right)
+\end{equation}
+
+$f^N_\text{leach}$ is the fraction of $N_\text{min}$ available to be leached, $F^W_\text{drainage}$ is drainage, and


Same as above

Alomir · 2026-06-05T16:51:06Z

-mineral nitrogen pool. The realized volatilization flux is proportional to $N_\text{min}$ and depends on temperature and
-soil moisture.
+$K_\text{vol}$ is the nitrogen volatilization rate constant that determines the maximum rate of N volatilization as a
+proportion of available $N_\text{min}$. The realized volatilization flux is proportional to available Nmin through Kvol and depends on temperature and soil moisture.


Agreed with copilot's recommendation

+\[
 D_{\text{temp,Q10}} = Q_{10}^{\frac{(T-T_\text{opt})}{10}}
-\label{eq:Braswell_A18b}
-\end{equation}
+\]


Sanketmandwal · 2026-05-28T04:59:35Z

Hello @dlebauer sir , I have made changes. Can you please review it once ? Tell me if any correction is there.

dlebauer

Thanks for these changes - sorry I reviewed and had suggestions but forgot to submit them. Please see comments in line.

dlebauer · 2026-05-28T06:53:04Z

 Moisture dependence functions are typically based on soil water content as a fraction of water holding capacity, also
-referred to as soil moisture or fractional soil wetness. We will represent this fraction of soil wetness
-as $f_\text{WHC}$.
+referred to as soil moisture or fractional soil wetness. SIPNET represents this fraction of soil wetness as


Suggested change

referred to as soil moisture or fractional soil wetness. SIPNET represents this fraction of soil wetness as

referred to as soil moisture or fractional soil wetness

dlebauer · 2026-05-28T06:53:25Z

-referred to as soil moisture or fractional soil wetness. We will represent this fraction of soil wetness
-as $f_\text{WHC}$.
+referred to as soil moisture or fractional soil wetness. SIPNET represents this fraction of soil wetness as
+$f_\text{WHC}$.


Suggested change

$f_\text{WHC}$.

($f_\text{WHC}$).

dlebauer · 2026-05-28T06:59:09Z

 | $N_{\text{org, litter},0}$        | litterOrgNInit | Initial litter organic nitrogen content                                  | $\text{g N} \cdot \text{m}^{-2}$                                    |                                                                                          |
 | $N_{\text{org, soil},0}$          | soilOrgNInit   | Initial soil organic nitrogen content                                    | $\text{g N} \cdot \text{m}^{-2}$                                    |                                                                                          |
-| $N_{\text{min, soil},0}$          | mineralNInit   | Initial soil mineral nitrogen content                                    | $\text{g N} \cdot \text{m}^{-2}$                                    |                                                                                          |
+| $N_{\text{min},0}$                | mineralNInit   | Initial mineral nitrogen content                                         | $\text{g N} \cdot \text{m}^{-2}$                                    | Single mineral N pool used by soil and litter N fluxes                                   |


Although this is a simplifying abstraction, even though both litter and soil contribute to this pool, it still functions as a soil mineral N pool because it is available to roots.

I'd prefer to keep the soil subscript, and use the description to clarify.

Updated as suggested, thanks

dlebauer · 2026-05-28T07:02:23Z

+| $K_\text{vol}$         | nVolatilizationFrac  | Nitrogen volatilization rate constant that determines the maximum rate of N volatilization as a proportion of available $N_\text{min}$ | $\text{day}^{-1}$ | \eqref{eq:n_vol}                 |
+| $f^N_{\text{leach}}$   | nLeachingFrac        | Fraction of $N_\text{min}$ available to be leached, applied after scaling by $\phi = \min(F^W_\text{drainage}/W_\text{WHC}, 1)$      | $\text{day}^{-1}$  | \eqref{eq:n_leach}               |


Should these both be f?

I kept $K_\text{vol}$ because SIP89 and issue #185 use K_vol for the volatilization rate constant, and it matches the implemented nVolatilizationFrac parameter and existing model equations. I used $f^N_\text{leach}$ for leaching to stay consistent with the current leaching notation and recent review comments. If you'd prefer both parameters to follow the same notation convention, I'm happy to update them consistently.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

+| Symbol                 | Parameter Name       | Definition                                                                                                                           | Units             | Notes                            |
+| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | -------------------------------- |
+| $K_\text{vol}$         | nVolatilizationFrac  | Nitrogen volatilization rate constant that determines the maximum rate of N volatilization as a proportion of available $N_\text{min}$ | $\text{day}^{-1}$ | \eqref{eq:n_vol}                 |
+| $f^N_{\text{leach}}$   | nLeachingFrac        | Fraction of $N_\text{min}$ available to be leached, applied after scaling by $\phi = \min(F^W_\text{drainage}/W_\text{WHC}, 1)$      | $\text{day}^{-1}$  | \eqref{eq:n_leach}               |


+\begin{equation}
+\phi = \min\left(\frac{F^W_\text{drainage}}{W_\text{WHC}}, 1\right)
+\end{equation}


Addressed

dlebauer · 2026-06-06T21:40:11Z

Thanks!

[185] Update N cycle documentation

8dfb534

Copilot AI review requested due to automatic review settings May 27, 2026 07:07

Sanketmandwal requested review from Alomir, dlebauer, mdietze and mswilburn as code owners May 27, 2026 07:07

Copilot AI reviewed May 27, 2026

View reviewed changes

Changes Made

2974311

Merge branch 'master' into 185-update-n-cycle-docs

aaa7489

dlebauer previously requested changes Jun 6, 2026

View reviewed changes

dlebauer requested a review from Copilot June 6, 2026 04:35

Copilot started reviewing on behalf of dlebauer June 6, 2026 04:36 View session

Copilot AI reviewed Jun 6, 2026

View reviewed changes

Address review comments on N cycle documentation

0135a6b

dlebauer enabled auto-merge (squash) June 6, 2026 21:40

dlebauer approved these changes Jun 7, 2026

View reviewed changes

dlebauer merged commit 7b2a515 into PecanProject:master Jun 7, 2026
12 of 13 checks passed

	referred to as soil moisture or fractional soil wetness. SIPNET represents this fraction of soil wetness as
	referred to as soil moisture or fractional soil wetness

		\| $K_\text{vol}$ \| nVolatilizationFrac \| Nitrogen volatilization rate constant that determines the maximum rate of N volatilization as a proportion of available $N_\text{min}$ \| $\text{day}^{-1}$ \| \eqref{eq:n_vol} \|
		\| $f^N_{\text{leach}}$ \| nLeachingFrac \| Fraction of $N_\text{min}$ available to be leached, applied after scaling by $\phi = \min(F^W_\text{drainage}/W_\text{WHC}, 1)$ \| $\text{day}^{-1}$ \| \eqref{eq:n_leach} \|

Uh oh!

Conversation

Sanketmandwal commented May 27, 2026

Summary

How was this change tested?

Reproduction steps

Related issues

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sanketmandwal commented May 28, 2026

Uh oh!

dlebauer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

dlebauer commented Jun 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants